---
title: ControllerUtils 控制器工具
icon: MousePointer2
relatedFile: app/src/core/service/controlService/controller/concrete/utilsControl.tsx
---

该服务提供了一系列实用功能，主要用于处理用户与项目画布中各类图形元素（如文本节点、边缘、区域、URL节点、传送门节点等）的交互与编辑。它负责管理文本输入、自动补全、元素尺寸调整、编辑状态的视觉反馈，并辅助进行对象选择与创建。

## 文本节点编辑

### `editTextNode(clickedNode: TextNode, selectAll = true)`

用于编辑画布中的文本节点。它会锁定相机、计算文本框的视图位置和样式（包括字体颜色、背景、边框等），并启用文本节点的编辑模式。支持文本输入、自动补全逻辑节点名称，并根据文本内容动态调整文本框大小。编辑完成后，会解锁相机并记录操作历史。

## 边缘文本编辑

### `editEdgeText(clickedLineEdge: Edge, selectAll = true)`

用于编辑普通边缘上的文本。它会锁定相机，计算文本框的视图位置，并提供一个文本输入区域供用户修改边缘文本。编辑完成后，解锁相机并记录操作历史。

### `editMultiTargetEdgeText(clickedEdge: MultiTargetUndirectedEdge, selectAll = true)`

与 `editEdgeText` 类似，但专门用于编辑多目标无向边缘上的文本。

## 节点标题编辑

### `editUrlNodeTitle(clickedUrlNode: UrlNode)`

用于编辑 URL 节点的标题。它会锁定相机，启用 URL 节点的标题编辑模式，并提供输入框供用户修改标题。编辑完成后，解锁相机并记录操作历史。

### `editSectionTitle(section: Section)`

用于编辑区域（Section）的标题。它会锁定相机，启用区域的标题编辑模式，并提供输入框供用户修改标题。编辑完成后，解锁相机并记录操作历史。

### `editPortalNodeTitle(clickedPortalNode: PortalNode)`

用于编辑传送门节点的标题。它会锁定相机，启用传送门节点的标题编辑模式，并提供输入框供用户修改标题。编辑完成后，解锁相机并记录操作历史。

## 节点详情编辑

### `editTextNodeHookGlobal`

一个全局对象，包含用于文本节点编辑开始和结束时的钩子函数，允许外部修改其行为。

### `editNodeDetailsByKeyboard()`

通过键盘快捷键触发，用于编辑当前选中节点的详细信息。如果没有选中节点，则会显示错误提示。

### `editNodeDetails(clickedNode: Entity)`

用于将指定节点设置为详细信息编辑模式，并触发 `editTextNodeHookGlobal` 中定义的开始编辑钩子函数。

## 节点添加与状态管理

### `addTextNodeByLocation(location: Vector, selectCurrent: boolean = false, successCallback?: (uuid: string) => void)`

在指定位置添加一个新的文本节点。如果该位置位于某个区域内，则新节点会添加到该区域中。添加成功后，会将新节点置于编辑模式。

### `addTextNodeFromCurrentSelectedNode(direction: Direction, selectCurrent = false)`

根据当前选中的节点，在指定方向上添加一个新的文本节点。添加成功后，会将新节点置于编辑模式。

### `textNodeInEditModeByUUID(uuid: string)`

根据 UUID 将指定的文本节点置于编辑模式，并为其添加创建闪烁特效。

## 交互检测

### `getClickedStageObject(clickedLocation: Vector)`

检测鼠标点击位置是否命中了画布上的某个舞台对象（实体或关联）。在宏观视野下，也会考虑区域的点击。

### `isClickedResizeRect(clickedLocation: Vector): boolean`

检测鼠标点击位置是否命中了当前选中文本节点的调整大小手柄。
